.\" $Id: PAPI_read_counters.3,v 1.10 2004/10/04 02:16:26 jthomas Exp $
.TH PAPI_read_counters 3 "September, 2004" "PAPI Programmer's Reference" "PAPI"

.SH NAME
PAPI_read_counters \- PAPI High Level: read and reset counters
.LP
PAPI_accum_counters \- PAPI High Level: accumulate and reset counters

.SH SYNOPSIS
.B C Interface
.nf
.B #include <papi.h>
.BI "int\ PAPI_read_counters(long_long *" values ", int " array_len ");"
.BI "int\ PAPI_accum_counters(long_long *" values ", int " array_len ");"
.fi
.B Fortran Interface
.nf
.B #include "fpapi.h"
.BI PAPIF_read_counters(C_LONG_LONG(*)\  values,\  C_INT\  array_len,\  C_INT\  check )
.BI PAPIF_accum_counters(C_LONG_LONG(*)\  values,\  C_INT\  array_len,\  C_INT\  check )
.fi

.SH DESCRIPTION
.LP
.B PAPI_read_counters(\|)
copies the event counters into the array
.I values
\.
 The counters are reset and left running after the call.
.LP
.B PAPI_accum_counters(\|)
adds the event counters into the array
.I values
\.
 The counters are reset and left running after the call.
.LP
These calls assume an initialized PAPI library and a properly added event set.

.SH ARGUMENTS
.I *values
-- an array to hold the counter values of the counting events
.LP
.I array_len 
-- the number of items in the *events array
.LP

.SH RETURN VALUES
On success, these functions return
.B "PAPI_OK."
 On error, a non-zero error code is returned. 

.SH ERRORS
.TP
.B "PAPI_EINVAL"
One or more of the arguments is invalid.
.TP
.B "PAPI_ESYS"
A system or C library call failed inside PAPI, see the 
.I "errno"
variable.

.SH EXAMPLES
.nf
.if t .ft CW
  do_100events();
  if (PAPI_read_counters(values, num_hwcntrs) != PAPI_OK)
    handle_error(1);
  /* values[0] now equals 100 */
  do_100events();
  if (PAPI_accum_counters(values, num_hwcntrs) != PAPI_OK)
    handle_error(1);
  /* values[0] now equals 200 */
  values[0] = -100;
  do_100events();
  if (PAPI_accum_counters(values, num_hwcntrs) != PAPI_OK)
    handle_error(1);
  /* values[0] now equals 0 */
.if t .ft P
.fi

.SH BUGS
These functions have no known bugs.

.SH SEE ALSO
.BR PAPI_start_counters "(3),"
.BR PAPI_set_opt "(3),"
.BR PAPI "(3)," PAPIF "(3)"
